﻿// -------------------------------------------------------------------------
//    @FileName         :    NFRawAllocator.h
//    @Author           :    gaoyi
//    @Date             :    2022/10/10
//    @Email			:    445267987@qq.com
//    @Module           :    NFRawAllocator
//    @Description      :    原始内存分配器，提供可跟踪的底层内存管理功能
//
// -------------------------------------------------------------------------

/**
 * @file NFRawAllocator.h
 * @brief 原始内存分配器
 * @details 该文件实现了一个底层内存分配器，提供可跟踪的内存管理功能，主要特性包括：
 * 
 * **核心功能：**
 * - **基础内存操作**：分配、重新分配、释放内存
 * - **内存跟踪**：可选的内存分配跟踪和调试支持
 * - **兼容接口**：与标准C库内存函数兼容的接口
 * - **调试支持**：详细的源码位置记录和泄漏检测
 * - **透明切换**：通过宏实现调试版本和发布版本的无缝切换
 * 
 * **设计理念：**
 * - **简单直接**：直接封装系统内存分配函数
 * - **可控跟踪**：条件编译支持，不影响发布版本性能
 * - **调试友好**：提供详细的内存分配信息用于问题诊断
 * - **接口统一**：提供一致的内存管理接口
 * 
 * **技术特点：**
 * - 零开销抽象（发布版本）
 * - 详细的调试信息收集（调试版本）
 * - 宏定义简化使用接口
 * - 与内存跟踪系统集成
 * 
 * **适用场景：**
 * - 底层内存管理需求
 * - 需要内存跟踪的模块
 * - 自定义内存分配策略
 * - 内存调试和分析
 * 
 * **使用模式：**
 * @code
 * // 创建分配器实例
 * NFRawAllocator allocator;
 * 
 * // 分配内存（推荐使用宏）
 * void* ptr = MallocBuf(1024);
 * 
 * // 重新分配
 * ptr = ReallocBuf(ptr, 2048);
 * 
 * // 释放内存
 * FreeBuf(ptr);
 * @endcode
 * 
 * @author gaoyi
 * @date 2022/10/10
 * @version 1.0
 */

#pragma once

#include "NFComm/NFCore/NFPlatform.h"
#include "NFComm/NFCore/NFSingleton.hpp"

/**
 * @class NFRawAllocator
 * @brief 原始内存分配器类
 * @details 提供底层内存分配功能，支持可选的内存跟踪和调试功能。
 * 
 * **核心特性：**
 * - **标准兼容**：提供与malloc/realloc/free兼容的接口
 * - **跟踪支持**：可选的内存分配跟踪功能
 * - **调试信息**：记录分配位置的详细源码信息
 * - **错误检测**：支持常见内存错误的检测
 * - **统计功能**：提供内存使用统计和分析
 * 
 * **设计考虑：**
 * - 作为其他内存管理组件的基础
 * - 提供可靠的底层内存操作
 * - 支持内存泄漏检测和分析
 * - 最小化性能开销
 * 
 * **实现策略：**
 * - 调试版本：详细跟踪每次内存操作
 * - 发布版本：直接调用系统函数，零开销
 * - 错误处理：安全的错误检测和报告
 * - 统计收集：可选的使用情况统计
 * 
 * **线程安全：**
 * @warning 该类本身不提供线程安全保证，需要外部同步
 * @note 内部调用的系统函数通常是线程安全的
 * 
 * **内存管理策略：**
 * - 直接使用系统内存分配器
 * - 不进行额外的内存池化
 * - 适合大块内存或不规则大小的分配
 * - 支持内存重新分配和动态调整
 */
class NFRawAllocator
{
public:
    /**
     * @brief 构造函数
     * 
     * 初始化原始内存分配器，准备内存管理功能。
     * 设置内部状态和统计信息。
     */
    NFRawAllocator();
    
    /**
     * @brief 析构函数
     * 
     * 清理分配器资源，确保没有内存泄漏。
     * 在调试模式下会报告未释放的内存。
     */
    ~NFRawAllocator();

    // ========================================================================
    // 基础内存分配接口
    // ========================================================================

    /**
     * @brief 分配内存
     * @param size 要分配的内存大小（字节）
     * @return 分配的内存指针，失败时返回nullptr
     * 
     * **功能说明：**
     * 分配指定大小的内存块，类似于标准的malloc函数。
     * 
     * **分配特点：**
     * - 直接调用系统内存分配器
     * - 不进行内存初始化
     * - 支持任意大小的内存请求
     * - 内存对齐遵循系统默认策略
     * 
     * **错误处理：**
     * - 大小为0时的行为遵循系统实现
     * - 内存不足时返回nullptr
     * - 不抛出异常，通过返回值表示错误
     * 
     * **性能特点：**
     * - 发布版本：直接系统调用，最优性能
     * - 调试版本：额外的跟踪开销
     * 
     * @note 分配的内存内容未定义，使用前应进行初始化
     * @warning 必须使用对应的Free方法释放内存
     */
    void* Alloc(size_t size);

    /**
     * @brief 重新分配内存
     * @param ptr 原内存指针，可以为nullptr
     * @param size 新的内存大小（字节）
     * @return 新的内存指针，失败时返回nullptr
     * 
     * **功能说明：**
     * 改变已分配内存块的大小，类似于标准的realloc函数。
     * 
     * **重分配行为：**
     * - ptr为nullptr时等价于Alloc(size)
     * - size为0时等价于Free(ptr)
     * - 扩大时保留原有数据，新增部分未初始化
     * - 缩小时保留前size字节的数据
     * 
     * **内存处理：**
     * - 可能返回新的内存地址
     * - 原内存内容会被保留或拷贝
     * - 失败时原内存保持不变
     * 
     * **性能考虑：**
     * - 扩大内存可能需要数据拷贝
     * - 系统可能就地扩展内存
     * - 避免频繁的重分配操作
     * 
     * @note 返回地址可能与原地址不同，需要更新指针
     * @warning 失败时原内存仍然有效，不会被自动释放
     */
    void* Realloc(void* ptr, size_t size);

    /**
     * @brief 释放内存
     * @param ptr 要释放的内存指针
     * 
     * **功能说明：**
     * 释放之前分配的内存块，类似于标准的free函数。
     * 
     * **释放行为：**
     * - ptr为nullptr时安全忽略
     * - 释放后指针变为野指针
     * - 内存立即归还给系统
     * 
     * **安全检查：**
     * - 调试版本可检测重复释放
     * - 调试版本可检测野指针释放
     * - 发布版本依赖系统实现的安全性
     * 
     * **性能特点：**
     * - 发布版本：直接系统调用
     * - 调试版本：额外的验证开销
     * 
     * @warning 释放后不得再次使用该指针
     * @note 建议释放后将指针设置为nullptr
     */
    void  Free(void* ptr);

public:
    // ========================================================================
    // 内存跟踪版本接口
    // ========================================================================

    /**
     * @brief 分配内存并记录跟踪信息
     * @param size 要分配的内存大小（字节）
     * @param file 调用所在的文件名
     * @param func 调用所在的函数名
     * @param line 调用所在的行号
     * @return 分配的内存指针，失败时返回nullptr
     * 
     * **功能说明：**
     * 分配内存并将分配信息记录到内存跟踪系统中。
     * 
     * **跟踪信息：**
     * - 完整的源码位置信息
     * - 内存大小和分配时间
     * - 调用堆栈（如果启用）
     * - 分配序号和标识
     * 
     * **调试价值：**
     * - 精确定位内存分配位置
     * - 检测内存泄漏的具体来源
     * - 分析内存使用模式
     * - 验证内存管理正确性
     * 
     * **使用场景：**
     * - 开发阶段的内存调试
     * - 内存泄漏问题排查
     * - 性能分析和优化
     * 
     * @note 只在CHECK_MEM_LEAK宏定义时生效
     * @see MallocBuf宏提供更简洁的调用方式
     */
    void* AllocTrack(size_t size,
                     const char* file,
                     const char* func,
                     uint32_t line);

    /**
     * @brief 重新分配内存并更新跟踪信息
     * @param ptr 原内存指针
     * @param size 新的内存大小（字节）
     * @param file 调用所在的文件名
     * @param func 调用所在的函数名
     * @param line 调用所在的行号
     * @return 新的内存指针，失败时返回nullptr
     * 
     * **功能说明：**
     * 重新分配内存并更新内存跟踪系统中的记录。
     * 
     * **跟踪更新：**
     * - 移除原内存的跟踪记录
     * - 添加新内存的跟踪记录
     * - 更新内存大小和位置信息
     * - 保持跟踪数据的一致性
     * 
     * **错误处理：**
     * - 失败时保持原跟踪记录不变
     * - 检测无效指针的重分配
     * - 记录重分配操作的详细信息
     * 
     * @note 只在CHECK_MEM_LEAK宏定义时生效
     * @see ReallocBuf宏提供更简洁的调用方式
     */
    void* ReallocTrack(void* ptr,
                       size_t size,
                       const char* file,
                       const char* func,
                       uint32_t line);

    /**
     * @brief 释放内存并移除跟踪记录
     * @param ptr 要释放的内存指针
     * 
     * **功能说明：**
     * 释放内存并从内存跟踪系统中移除相应的记录。
     * 
     * **跟踪清理：**
     * - 验证释放操作的有效性
     * - 从跟踪系统移除分配记录
     * - 检测重复释放等错误
     * - 更新内存使用统计
     * 
     * **错误检测：**
     * - 检测释放未分配的内存
     * - 检测重复释放操作
     * - 记录释放操作的位置信息
     * 
     * @note 只在CHECK_MEM_LEAK宏定义时生效
     * @see FreeBuf宏提供更简洁的调用方式
     */
    void  FreeTrack(void* ptr);
};

// ========================================================================
// 便捷宏定义 - 根据编译模式选择实现
// ========================================================================

#ifdef CHECK_MEM_LEAK
    /// @brief 分配内存宏（调试版本），自动传递源码位置信息
    #define  MallocBuf(SIZET)         AllocTrack(SIZET, __FILE__, __FUNCTION__, __LINE__)
    
    /// @brief 重新分配内存宏（调试版本），自动传递源码位置信息
    #define  ReallocBuf(PTRT, SIZET)  ReallocTrack(PTRT, SIZET, __FILE__, __FUNCTION__, __LINE__)
    
    /// @brief 释放内存宏（调试版本），自动记录释放操作
    #define  FreeBuf                  FreeTrack
#else
    /// @brief 分配内存宏（发布版本），直接调用分配函数
    #define  MallocBuf(SIZET)         Alloc(SIZET)
    
    /// @brief 重新分配内存宏（发布版本），直接调用重分配函数
    #define  ReallocBuf(PTRT, SIZET)  Realloc(PTRT, SIZET)
    
    /// @brief 释放内存宏（发布版本），直接调用释放函数
    #define  FreeBuf                  Free
#endif  // CHECK_MEM_LEAK

